home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / earcd / dev / misc / makedt_1.lha / MakeDT.doc < prev    next >
Text File  |  1997-02-09  |  11KB  |  253 lines
  1. MakeDT.doc - documentation for MakeDT.rexx
  2. $VER: MakeDT.doc 1.3 (17.11.96)
  3. Written by Michal Letowski
  4.  
  5.  
  6.                           ### Table Of Contents ###
  7.  
  8. 1. Disclaimer
  9. 2. Introduction
  10. 3. How To?
  11. 4. Usage
  12. 5. Other Files
  13. 6. History
  14. 7. Author Info
  15.  
  16.  
  17.                             *** 1. Disclaimer ***
  18.  
  19.     This program is given 'as is'. No warranty is given or implied. Use it
  20. at your own risk. In fact, I expect some informations in this document to be
  21. inaccurate and incomplete. This document is based only on Commodore's Includes
  22. and AutoDocs, some experiments and (many) assumptions. If you know better,
  23. please feel free to make corrections.
  24.     This program and documentation are placed in Public Domain - do with
  25. them whatever you want. If you have ANY opinion on my work, PLEASE send me an
  26. E-Mail message - I like the feedback.
  27.  
  28.  
  29.                            *** 2. Introduction ***
  30.  
  31.     Workbench 3.0 introduced cool new feature: DataTypes. DataTypes
  32. provide common ground for dealing with different types of data found on modern
  33. computers. With DataTypes you don't have to worry about complexities of file
  34. formats. For example, a paint program using DataTypes could load any type of
  35. pictures: ILBM's, GIF's, JPEG's etc. and save in any of the formats supported.
  36. Or you could load/save different formats of sound samples. The DataTypes can
  37. deal with any kind of data.
  38.     Another advantage of DataTypes is OLE (Object Linking and Embedding).
  39. This technique is already used on PC's and Macs. It allows a program to
  40. transfer control on an object to another program. With OLE you could import a
  41. picture into your favourite wordprocessor and then just by clicking on it call
  42. a paint program, which would automatically load this picture.
  43.     And I should mention DataTypes' ability to recognize type of data:
  44. even if they don't know what to do with a file, they can tell you what this
  45. file contains. This is similar to features of some Public Domain programs:
  46. WhatIs and CFX, for example. But DataTypes have an advantage of being
  47. sanctioned by Commodore, which makes them available to everyone.
  48.     Unfortunately, these capabilities still wait to be uncovered. Very few
  49. programs actually use DataTypes. In fact, only Workbench programs and some
  50. viewers take advantage of them. This is partially due to the fact, that there
  51. is very little documentation about DataTypes.
  52.     My goal is to change it. This program will let you create new
  53. DataTypes (well, only part of them) easily. It isn't the best program in the
  54. world (I'm writing a full-featured DataTypes editor) but it's usable. What's
  55. more - it has some advantages over Commodore's DTDesc (eg. you can specify
  56. tags, tools and choose your own TypeID). As an added bonus, MakeDT comes with
  57. source, so you can modify it to suit your needs.
  58.  
  59.  
  60.                               *** 3. How to? ***
  61.  
  62.     DataTypes sub-system consists of 3 parts:
  63. · datatypes.library is located in your LIBS: directory and is necessary to do
  64. anything.
  65. · files located in LIBS:DataTypes/ (they end with '.datatype') are responsible
  66. for translating different formats. These are quite complicated programs and
  67. require good amount of knowledge and programming skills to write.
  68. Unfortunately, my program doesn't allow you to create them :-(yet :-).
  69. · files located in DEVS:DataTypes/ are used to recognize type of a file. They
  70. are stored in IFF format and will be our main area of interest. From now by
  71. DataTypes I will mean only these files.
  72.     Additionally, there is AddDataType command located in C: directory.
  73. If you create or modify a DataType you should type
  74. AddDataType <DataType name with path> REFRESH
  75. in Shell window - otherwise new DataType will not be recognized.
  76.  
  77.                        *** 3a File type recognition ***
  78.  
  79.     There are 3 methods for detecting file's type:
  80. · file name matching;
  81. · file contents matching;
  82. · custom function.
  83.     The first method uses simple AmigaDOS pattern matching to recognize
  84. type of a file. For example, you could enter '#?.info' to select icon files or
  85. '.backdrop' for detecting Workbench backdrops. Any valid AmigaDOS pattern can
  86. be used. This method is very fast (as it doesn't involve opening a file and
  87. reading from it), but not accurate. On Amiga, files rarely have to have
  88. special extension (in contrast to PC world, where many programs rely strictly
  89. on names conventions). As such it should be used with some caution and only if
  90. more advanced methods can't be used.
  91.     The second method is more flexible. It bases on a fact that programs
  92. usually write their own unique headers when saving data. If this is true, then
  93. we are able to determine type of a file just by looking at its contents. For
  94. example every GIF picture has 'GIF87a' or 'GIF89a' string at the beginning. To
  95. utilize this method you provide up to 64 chars that should match first chars
  96. in a file. You can also use 'match any' char. For GIF's this would look like
  97. 'GIF8?a' - the question mark matches '7' or '9'. It is advised, that you have
  98. some documentation describing the format so you won't make false assumptions.
  99.     Last method is the most flexible one. But... you have to be a
  100. programmer and write a program (in C or Assembler). This program will then
  101. look at file to check if it contains data proper for a given format. This
  102. method is used for Commodore's MacPaint DataTypes. For more details look at
  103. include files.
  104.  
  105.                            *** 3b Identification ***
  106.  
  107.     Each DataType is identified by 4 strings:
  108. · <name> is a descriptive name of a DataType. It appears in MultiView after
  109. selecting About. This name may be of arbitrary length and may contain spaces.
  110. · <base name> indicates which .datatype library should be used to interpret
  111. file's contents. ".datatype" is appended to <base name> and such string is
  112. used by DataTypes to open a library. For your own DataTypes (which don't
  113. usually come with an interpreter) you should perhaps use "binary", "exe" (for
  114. executables) or "cli". [Note: binary.datatype, exe.datatype and cli.datatype
  115. are 3rd party DataTypes available eg. on Aminet://util/dtype.]
  116. · <group id> identifies a group that the file belongs to. Currently defined
  117. groups are:
  118.     · syst (System) - system files;
  119.     · text (Text) - textual files;
  120.     · docu (Document) - documents (spreadsheet data, text with pictures etc.);
  121.     · soun (Sound) - sound samples;
  122.     · inst (Instrument) - musical instruments;
  123.     · musi (Music) - songs;
  124.     · pict (Picture) - graphics;
  125.     · anim (Animation) - animations;
  126.     · movi (Movie) - animation with sound.
  127.  
  128. · <type id> is up to 4 chars long and (as <group id>) case sensitive. It must
  129. also be unique and should be lower-cased.
  130.  
  131.                           *** 3c Other features ***
  132.  
  133.     Each DataType may have some tags stored. But don't ask me what they
  134. are used for...
  135.     Additionally, DataType can contain tool description for use with OLE
  136. (or at least I think so). Unfortunately, no programs seems to take advantage
  137. of this, so I was unable to test this feature. However it's there...
  138.  
  139.  
  140.                                *** 4. Usage ***
  141.  
  142.     MakeDT works in batch mode. You prepare description file and give it
  143. as a parameter. MakeDT will process it and create DataType description.
  144.     Description file is an ASCII file. Each line begins with a command
  145. word and it's parameters after '=' sign. Lines beginning with a '#' 
  146. ('hash') are skipped.
  147.     Commands and parameters enclosed in [] can be omitted.
  148.     Available commands (case is not important):
  149.  
  150. [FileName]=<Where description should be placed>
  151.     Specifies name of DataType recog file (overridden by a CLI parameter).
  152.  
  153. DTName=<name>,<basename>
  154.     <name> is the name of the DataType, as described in chapter 3b. For
  155. conformance to Commodore's DTDesc, it should be the same as file part of
  156. <FileName>.
  157.     <basename> is equivalent to <base name> described in chapter 3b.
  158.  
  159. [Version]=<version>.<revision>
  160.     <version> is a major version number of the DataType.
  161.     <revision> is a minor version number of the DataType.
  162.  
  163. ID=<group id>,<type id>
  164.     As described in chapter 3b.
  165.  
  166. Recog=<file name pattern>[,<contents pattern>]
  167.     Recognition patterns, as described in chapter 3a. <file name pattern>
  168. is an AmigaDOS pattern to match file name ('#?' for 'match any'). <contents
  169. pattern> is a pattern to match file's contents. <contents pattern> may
  170. contain:
  171.     · strings (eg. 'FORM'), one letter for one byte of a file#
  172.     · hexadecimal values (one for each byte), preceded by '\$' 
  173. chars(eg. \$00\$00 for two NUL characters);
  174.     · 'match any' chars (one for each byte) in '\?' form;
  175.     · to include '\' char enter '\\'.
  176.     <contents pattern> is optional.
  177.     As an example, GIF file (see chapter 3a) could be described as follows:
  178. Recog=#?.gif                    # Only files with #?.gif extension are matched
  179. Recog=#?,GIF8\?a                # Any name is matched and the file must begin
  180.                                 # with 'GIF8' string
  181. Recog=#?,\$47\$49\$46\$38\?\$61 # As above, but using hexadecimal encoding
  182.  
  183. Flags=<type=Binary|ASCII|IFF|Other>,<case=y|n>,<priority>
  184.     Flags for the DataType. <type> is general type of a file. <case>
  185. specifies whether file-contents matching should be case-sensitive ('y') or
  186. case-insensitive ('n'). For binary files this should be 'y', for ASCII files
  187. - depending on file type. <priority> describes the order in which DataTypes
  188. are checked when trying to recognize file type. <priority> must be in 0-65535
  189. range. DataTypes with higher priority are checked first. Typical priority is
  190. 0.
  191.  
  192. [Code]=<name of file containing recog function>
  193.     If you use custom function for recognition (see chapter 3a), enter
  194. name of the executable file here. Otherwise don't include this tag.
  195.  
  196. [Tool]=<type=INFO|BROWSE|MAIL|EDIT|PRINT>,<name>,<start=CLI|WORKBENCH|AREXX>
  197. [Tool]=
  198. ...
  199. [Tool]=
  200.     Each <Tool> describes DataType's tool (as described in chapter 3c).
  201. <type> is type of the tool, <name> is the name of the tool <start> specifies
  202. how the tool should be started.
  203.  
  204. [Tag]=<tag>,<tag value>
  205. [Tag]=
  206. ...
  207. [Tag]=
  208.     Each <Tag> describes one DataType tag (chapter 3c). <tag> is a decimal
  209. or hexadecimal (if preceded by '$') number describing tag. <tag value>
  210. contains value for the tag and may also be either decimal or hexadecimal.
  211.  
  212.     As a minimum, you must provide DTName, ID, Recog and Flags commands.
  213.  
  214.  
  215.                             *** 5. Other Files***
  216.  
  217.     In Example directory you will find several example descriptions.
  218.     CatIFF.rexx lets you join several description files into one for
  219. faster load and to save disk space. Joined files are processed correctly by
  220. Commodore's DataTypes system.
  221.  
  222.  
  223.                               *** 6. History ***
  224.  
  225. 1.0 (20.12.94) - not released
  226. 1.1 (22.11.94) - first public version
  227. 1.2 (29.1.96)  - second public version
  228.     + now can write FVER chunk
  229.     ! fixed bug in tags conversion
  230. 1.3 (17.11.96) - 3rd public version
  231.     ! fixed numerous bugs
  232.  
  233.  
  234.                             *** 7. Author Info ***
  235.  
  236.     My name is Michal Letowski, I'm 24 years old. I hold Master degree in
  237. Computer Science from Technical University of Wroclaw. I work as an
  238. information science teacher in XXIV Secondary School in Wroclaw.
  239.  
  240. S-Mail address:
  241.  
  242. Przyjazni 51/17
  243. 53-030 Wroclaw
  244. POLAND
  245.  
  246. E-Mail address:
  247.  
  248. milet@geocities.com
  249.  
  250. WWW address:
  251.  
  252. http://www.geocities.com/CapeCanaveral/Lab/2769/
  253.